Formulas are strings, which are evaluated by an instance of the NFormulaEngine class. The formula evaluation produces a single NVariant instance - i.e. the result of the formula evaluation. The following example shows how to evaluate formulas:

NFormulaEngine formulaEngine = new NFormulaEngine();
NVariant res;

res = formulaEngine.Evaluate("10 + 20");
Console.WriteLine("10 + 20 evaluates to " + res);

res = formulaEngine.Evaluate("10mm + 20in");
Console.WriteLine("10mm + 20in evaluates to " + res);

res = formulaEngine.Evaluate("MIN(10, 20, 30)");
Console.WriteLine("MIN(10, 20, 30) evaluates to " + res);

res = formulaEngine.Evaluate("SUM(10, 20, 30)");
Console.WriteLine("SUM(10, 20, 30) evaluates to " + res);

You can use operators and functions in formulas to perform diverse operations on values of different types.

The rest of this topic focuses on the formula basics, variants and the operators.

See Functions for more information about the available functions.

A valid formula is such a string, which is lexically and grammatically correct. 

Formulas are constructed from tokens. Tokens are such substrings from the initial formula string, which cannot be broken into other tokens. A lexically correct formula consists of the following set of tokens:

• Parenthesis - the '(' and ')' characters, which are used to change the operators privilege and enclose the functions arguments.
• Curly Brackets - the '{' and '}' characters, which are used to create a block scope in the formula.
• Square Brackets - the '[' and ']' characters, which are used to enclose measurement units.
• Operators - the predefined operators, which you can use (+,-,*,\,<,> etc.)
• Commas - the ',' character, which is used to separate the function arguments.
• Semi Colons - the ';' character, which is used to separate the statements in block scope or the root scope.
• Number Constants - these are integer and floating point number constants. Following are some correctly formatted numbers:
  12; 0.1; 145.23; 7.5E-17; 8.234E+13
• String Constants - - these are substrings of the formula, which are enclosed in " (quote) characters. Following are some correctly formatted strings:
  ="hello"; ="world"
• Identifiers - an identifier is such a sub-string from the formula that starts with a letter, '_' or '$' sign and is followed by a sequence of letters, digits, '_', '$' and '.' chars.

The formula engine first splits the input formula to a valid set of tokens, that it further processes to construct a grammatically valid tree representation of the formula. The formula tree consists of the following types of elements:

• Root Element
  The root element is the root of the elements tree and is created by default. It is a scope element, meaning that you can use the ';' (semi-colon) to separate statements in the root scope.
  
• Block Elements
  These are scope elements that may contain multiple statements separated with the ';' (semi-colon) char. Block elements are created for the parts of the formula that are enclosed in '{' '}' (curly brackets).
  
• Constant Elements
  These are formula tree elements that always evaluate to a constant NVariant value. Constant elements are created for number and string tokens, as well as for identifiers that are equal to the true and false boolean value keywords. For example:
  
  - constant numbers: 12; 0.1; 145.23; 7.5E-17; 8.234E+13
  - constant strings: "hello"; "world"
  - constant booleans: true; false
  
• Standard Operator Elements 
  Standard operator elements are created for tokens that were recognized as valid operator tokens (+,-,*,\,<,> etc.). Operator elements perform a specific operation upon two arguments (binary operators) or single argument (unary operators). For example:
  
  - binary operators: 2 + 2 will evaluate to 4
  - unary operators: -2 will evaluate to -2
  
• Unit Operator Elements
  Unit operator elements are created for formula substrings that are enclosed in '[' ']' (square brackets). Unit operator elements are unary operators that multiple a value with a certain measurement unit. A number value associated with a measurement unit is called measure. Measurement unit algebra rules apply for measures. For example:
  
  10 [mm] + 20 [in] evaluates to 518 [mm]
  
• Function Elements
  Function elements are created for identifier tokens that reference a valid function name and are followed by the '(' (left parenthesis token). Supported is a large set of mathematical, trigonometric, logical, text, date-time and bitwise functions. Function arguments must be enclosed in parenthesis and divided by commas (see Functions). For example:
  
  MIN(10, 20) - evaluates to 10; COS(0) - evaluates to 1.
  
• Local Variable Elements
  Local variables are identifier tokens that reside on the left side of the assignment operator. Each local variable is considered declared for a specific scope.
  
• Global Variable Elements
  Variables elements are formula tree elements that evaluate to a variable NVariant value. The formula engine dynamically queries for variables and their values via the INVariableProvider interface.

The formula evaluation works with variants. The result of each formula evaluation is a variant too (e.g. a value of certain type - see Variants below).

Variants are represented by instances of the NVariant structure. Variants are value-type pairs, which facilitate the type conversion of values, as well as the operations with values of different type.

When variants are used in functions or operators that require a value of a certain type, variants are automatically converted to a value of this type. There are several distinct types of variants:

• Empty
  An empty variant holds no value. It is equivalent to null or DBNull. An empty variant can only be converted to string (as the "EMPTY()" string constant).
  
• Boolean
  Holds a boolean true or false value. Boolean variants can be automatically converted to:
  - string - as the "false" and "true" string constants respectively. 
  - number - as the 0 or 1 number values respectively. 
  
• Number
  Holds a floating point or integer number, with some precision (for example an Int32 number variant holds an integer value in 32 bits). When performing arithmetic operations number variants automatically change their type to ensure that they can hold the resulting value. Converting floating point numbers to integer numbers removes the decimal portion of the value. You can format numbers with the FORMAT function. Number variants can be automatically converted to:
  - string - by default used is the en-US culture.
  - boolean - as boolean false if number is zero, as boolean true otherwise.
  
• String
  Holds a text string. Strings can be automatically converted to:
  - boolean - to boolean false, if string is equal to "false", "FALSE" or "False" and to boolean true if string is equal to "true", "TRUE" or "true".
  - number - if the string contains a valid number (by default used is the en-US culture)
  - date time - if the string contains a valid date time (by default used is the en-US culture)
  
• Date Time
  Holds a date time value. Date-time variants can be converted only to string (by default using the en-US culture) and can be formatted with the FORMAT function.
  
• Measure 
  Holds a number value associated with a certain measurement unit. Measurement unit algebra rules apply to arithmetic operations with measures. Measures can be converted to:
  - strings - the value part by default uses the en-US culture, followed by the string representation of the unit.
  - booleans - as boolean false if value part is zero, as boolean true otherwise.
  - numbers - only if the unit has no dimension (like the radians unit for example).
  
• Array - holds an array of other variants.

The power of variants is their ability to provide transparent handling of type and measurement unit conversion so that you can perform common mathematical and logical operations, without caring for the actual type of the involved values. For example:

NVariant res1 = new NVariant(20) + new NVariant(30.0);
Console.WriteLine("Addition operator result with numbers: " + res1.ToString());

NVariant res2 = new NVariant(10, NUnit.Millimeter) + new NVariant(20, NUnit.Inch);
Console.WriteLine("Addition operator result with measures: " + res2.ToString());

NVariant res3 = new NVariant(10, NUnit.Meter) / new NVariant(20, NUnit.Second);
Console.WriteLine("Division operator result with measures: " + res3.ToString());

NVariant res4 = new NVariant(10, NUnit.Millimeter) > new NVariant(8, NUnit.Inch);
Console.WriteLine("Comparision operator result: " + res4.ToString());
// Output is:
// Addition operator result with numbers: 50
// Addition operator result with measures: 518 [mm]
// Division operator result with measures: 0.5 [m/s]
// Comparison operator result: false

You can use operators in formulas to perform arithmetic, comparison, logical and bitwise operations as described by the following table:

There is a certain precedence assigned to each operator. If an expression contains several operators, which are not enclosed in parentheses, the operator with the highest precedence is evaluated first. For example:

10 + 20 * 2 - evaluates to 50, because the multiplication operator will be evaluated first (it has a higher precedence than the addition operator).

(10 + 20) * 2 - evaluates to 60, since the parentheses override the default way in which the expression is evaluated.

The following table summarizes the operators precedence, in high to low order.

There is also a left or right associativity assigned to each operator. The associativity determines the execution order of operators with the same precedence. The Assignment (=) and the Exponentiation (^) operators have right associativity. All other operators have left associativity.

To demonstrate the effect of right versus left associativity consider the following expression:

5^2^3 - evaluates to 390625 (5^(2^3) = 390625), which is different than (5^2)^3=15625, because the Exponentiation has right associativity.

DOM